home *** CD-ROM | disk | FTP | other *** search
/ Visual Basic Toolbox / Visual Basic Toolbox (P.I.E.)(1996).ISO / database / dbawarco / dbawarco.txt < prev    next >
Encoding:
Text File  |  1995-11-19  |  7.6 KB  |  221 lines
  1. (c) Copyright 1995 MitranoSoft
  2.     All Rights Reserved
  3.     This product cannot be sold without permission from the author,
  4.     however it can be distributed freely, but only in the entirety of 
  5.     the bundled files.  For details, see the file License.txt bundled 
  6.     herein.
  7.  
  8. DBAwareCollection is a plug-compatible replacement of the VB4 Collection 
  9. object, but offers extended capabilities by adding the following object-
  10. and database-oriented features:
  11.  
  12.     Object persistence through database tables
  13.  
  14.     Automatic implementation of the object containment hierarchy
  15.  
  16.     Automatic instantiation of contained objects
  17.  
  18.     Encapsulated SQL services
  19.  
  20.     Mapping of objects to their underlying tables
  21.  
  22. It includes a public interface for various database-related and other 
  23. services, including:
  24.  
  25.     Returning the underlying RecordSet for use with the DataControl
  26.     object
  27.         Ex:
  28.             Set Data1.RecordSet = MyDBAwareCollection.RecordSet
  29.  
  30.     Setting various database-related parameters, such as the Database 
  31.     object, WhereClause, OrderByClause
  32.  
  33.     Adding new methods beyond the "Add", "Item" and "Remove" methods 
  34.     found in the VB4 Collection object, such as "Replace", "Refresh", 
  35.     "RecordSet", "RefreshRecordSet", "Remove",     "InstantiateFromDatabase", 
  36.     "InstantiateFromRecordSet", "CloneRecordSet", "CollectionIndex", 
  37.     "SetDatabaseParameters", "WhereClause", "OrderByClause" and many 
  38.     more
  39.  
  40. DBAwareCollection can function as a direct replacement for the VB4 
  41. Collection object.  The developer simply adds the two provided Class 
  42. Modules to the VB project, then replaces all references to the VB4 
  43. Collection object with references to the DBAwareCollection.
  44.  
  45.     Add these Classes:
  46.         DBAwareCollection.cls (File=DBAwarCO.cls)
  47.         DBAwareObjectLink.cls (File=DBAwarLK.cls)
  48.  
  49. By default, DBAwareCollection operates in "Collection-Emulation" mode, 
  50. such that there are no attempted database references.  This allows for 
  51. the creation of the non-visual Business Object Model (which is highly 
  52. recommended) without the need for an underlying database model (the 
  53. database modeling process is greatly simplified if it is deferred until 
  54. after the BOM has been finalized, anyway.)  When the database model is 
  55. complete, the developer modifies the database model as follows:
  56.  
  57.     Table "DBAwareObjectLinks" must be created, as found in the file 
  58.     VB4OO.MDB:
  59.         Column: FromObjectType    Text 50     PrimaryKey, Index1
  60.         Column: FromObjectID    Long         PrimaryKey, Index1
  61.         Column: ToObjectType    Text 50    PrimaryKey, Index2
  62.         Column: ToObjectID    Long        PrimaryKey, Index2
  63.  
  64.     All application Tables must be defined or attached to the same 
  65.     Database used to contain Table "DBAwareObjectLinks"
  66.  
  67.     Each of the supported Tables must have a Column as follows:
  68.         Name: ObjectID, Type: Counter
  69.  
  70. The BOM objects should be modified as follows:
  71.  
  72.     Public ObjectID as Long 
  73.         (to be mapped to Column "ObjectID" of the corresponding 
  74.         Table)
  75.         
  76.     Private MyCollection As New DBAwareCollection
  77.         (for each contained object collection)
  78.  
  79.     Public MyDatabase as Database
  80.         (probably necessary only once per project)
  81.  
  82.     Private Sub Class_Initialize:
  83.         ObjectID = -1
  84.         (possibly more code, as needed)
  85.  
  86.     Public Function InitializeFromRecordSet(RecordSet) As Long
  87.         Copies values from the RecordSet into the object's variables
  88.         Ex: 
  89.             Public Function InitializeFromRecordSet(RecordSet) _
  90.             As Long
  91.                 pvtFirstName = RecordSet("FirstName")
  92.                 pvtLastName  = RecordSet("LastName")
  93.                 InitializeFromRecordSet = Err
  94.             End Function
  95.  
  96.     Public Function InitializeRecordSet(RecordSet) As Long 
  97.         Copies values from the object's variables into the
  98.         RecordSet, but NOT "ObjectID" (this is in italics, by the 
  99.         way)
  100.         Ex: 
  101.             Public Function InitializeRecordSet(RecordSet) As Long
  102.                 RecordSet("FirstName") = pvtFirstName
  103.                 RecordSet("LastName")  = pvtLastName
  104.                 InitializeRecordSet = Err
  105.             End Function
  106.  
  107.     Public Function NewInstanceOfMyClass() as <Me>
  108.         Instantiates and returns a new object of this Class, where
  109.         "<Me>" is replaced with the appropriate Class Type
  110.         Ex: 
  111.             Public Function NewInstanceOfMyClass() As Person
  112.                 Set NewInstanceOfMyClass = New Person
  113.             End Function
  114.  
  115.     Public Function ObjectType() As String
  116.         Returns the type of object
  117.         Ex: 
  118.             Public ObjectType() As String
  119.                 ObjectType = "Person"
  120.             End Function
  121.  
  122.     Public Function TableName() as String
  123.         Returns the name of the underlying Table
  124.         Ex: 
  125.             Public TableName() As String
  126.                 TableName = "PersonMaster"
  127.             End Function
  128.  
  129.     Public Function <CollectionName> _
  130.         (Optional ByVal ObjectID As Variant) As Variant
  131.         Returns a DataAwareCollection.  Note the difference between 
  132.         the example described in the VB Programmer's Guide (as 
  133.         follows):
  134.             Public Function Persons(Optional ByVal ObjectID As _
  135.                 Variant) As Variant
  136.                 If Not IsMissing(ObjectID) Then
  137.                     Set Persons = 
  138.                         pvtPersonsCollection.Item(ObjectID)
  139.                 Else
  140.                     Set Persons = pvtPersonsCollection
  141.                 End If
  142.             End Function
  143.  
  144.         and the DataAwareCollection-compatible version: 
  145.             Public Function Persons(Optional ByVal ObjectID As _
  146.                 Variant) As Variant
  147.             ' Returns a DBAwareCollection of Person objects which 
  148.             '   are contained by this Company object,
  149.             ' or
  150.             ' Returns a Person object whose ObjectID matches the 
  151.             '   ObjectID parameter.
  152.  
  153.                 Dim tempNewPerson as New Person
  154.  
  155.                 If Not _
  156.                 pvtPersonsCollection.DatabaseHasBeenReferenced _ 
  157.                 Then
  158.                 pvtPersonsCollection.SetDatabaseParameters _
  159.                         Database:=MyDatabase, _
  160.                         OrderByClause:= _ 
  161.                         "LastName ASC, FirstName ASC"
  162.  
  163.                     Set pvtPersonsCollection = _
  164.                 pvtPersonsCollection.InstantiateFromDatabase( _
  165.                             Parent:=Me, _
  166.                             SampleObject:=tempNewPerson)
  167.                 End If
  168.     
  169.                 If Not IsMissing(ObjectID) Then
  170.                     Set Persons = _
  171.                  pvtPersonsCollection.Item(ObjectID)
  172.                 Else
  173.                     Set Persons = pvtPersonsCollection
  174.                 End If
  175.             End Function
  176.  
  177. The following general requirements must be met:
  178.  
  179.     The application must prepare a Database object for use
  180.  
  181.     The application must provide DBAwareCollection with the prepared
  182.     Database object using any of the following methods:
  183.         1.    the DBAwareCollection "Public Property Set Database" 
  184.             method,
  185.         2.      the DBAwareCollection "Database:=" named parameter of 
  186.             the "InstantiateFromDatabase" method
  187.         3.    the "Database:=" named parameter of the 
  188.             DBAwareCollection "SetDatabaseParameters" method
  189.  
  190. The following general recommendations should be considered:
  191.     Each object which contains a DBAwareCollection object should have 
  192.     a corresponding method named "Add<ContainedObjectType>" (e.g., 
  193.     "AddPerson", "AddAddress", etc.)  This serves as a wrapper which 
  194.     relieves the remainder of the application from    having to use 
  195.     "Persons.Add" (which requires the "Parent:=Me" nuisance parameter 
  196.     for correct object containment effectiveness)
  197.         Ex: 
  198.             Public Function AddPerson(Optional ByVal Item As _
  199.                 Variant As DBAwareCollection
  200.                 Set AddPerson = Me.Persons.Add( _
  201.                     Item:=Item, _
  202.                     Parent:=Me)
  203.             End Function
  204.  
  205.         The referenced "Add" method would also be necessary.
  206.  
  207. Please feel free to contact me if you have any questions regarding this 
  208. project.  I can be reached at:
  209.     CompuServe: 73367,3470
  210.     MSN:        KenFitzpatrick
  211.  
  212. This is a Shareware product.  Those who agree to pay a registration fee 
  213. of $45, will be kept up-to-date with future releases.  Refer to the file 
  214. Order.txt for registration information.
  215.  
  216. I sincerely believe DBAwareCollection will become a strategic component 
  217. of every VB Programmer's toolbox.
  218.  
  219. Thank you and best wishes.
  220.  
  221. Microsoft Visual Basic is a registered trademark of the Microsoft Corporation.